znp_interface.c File Reference
Interface to the Zigbee Network Processor (e.g. CC2530ZNP).
More...
#include "znp_interface.h"
#include <string.h>
#include "../HAL/hal.h"
#include "znp_interface_spi.h"
Detailed Description
Interface to the Zigbee Network Processor (e.g. CC2530ZNP).
This file contains library methods that implement the CC2530ZNP interface specification as well as error checking and return values.
Requires one physical interface file to be included, znp_interface_spi.h
- Note:
- To output SPI transmit information, define ZNP_INTERFACE_VERBOSE. It is recommended to define this on a per-project basis. In IAR, this can be done in Project Options : C/C++ compiler : Preprocessor In the defined symbols box, add: ZNP_INTERFACE_VERBOSE
- See also:
- http://processors.wiki.ti.com/index.php/Tutorial_on_the_Examples and http://e2e.ti.com/support/low_power_rf/default.aspx
- Rev
- 715
- Author
- dsmith
- Date
- 2010-08-19 10:49:20 -0700 (Thu, 19 Aug 2010)
YOU ACKNOWLEDGE AND AGREE THAT THE SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL TEXAS INSTRUMENTS OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.
Function Documentation
| unsigned char* getConfigurationParameter |
( |
unsigned char |
configId |
) |
|
Retrieves the given configuration parameter from the ZNP.
- Parameters:
-
| configId | the configuration parameter to retrieve. See Interface Spec for list of valid config parameters. Not checked for validity. |
- Returns:
- pointer to beginning of configuration parameter
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
- Note:
- does not verify configId is a valid configId
-
does not verify length returned in the SRSP matches what the length should be for that configId.
| void getDeviceInformation |
( |
|
) |
|
Displays the radio's device Information Properties. Device Information Properties include:
- Device State indicates whether the ZNP is on a network or not, and what type of device it is. This is a handy thing to check if things aren't operating correctly. If the device is starting as a coordinator, you'll see states of 01, 08, 08, then 09 once it has fully started.
- MAC Address (aka IEEE Address) is a globally unique serial number for this IC.
- Device Short Address is a network address assigned by the coordinator, similar to an IP Address in DHCP. The Coordinator always has a Short Address of 0.
- Parent MAC Address is the IEEE Address of this device's "parent", i.e. which device was used to join the network. For a router, once joined this parent MAC address is irrelevant. This DIP will NOT be updated if the network reforms. For an end-device then this parent MAC address will always specify which router the end-device is joined to.
- Channel is which frequency channel the device is operating on.
- PAN ID (Personal Area Network Identifier) of the network is a unique number shared for all devices on the same network.
- Extended PAN ID of the network is the coordinator's MAC Address.
If device is not connected to a network then the Short Address fields will be 0xFEFF, the Parent MAC Address and channel will be 0, and the Extended PAN ID will be this device's MAC Address.
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| unsigned char* getDeviceInformationProperty |
( |
unsigned char |
dip |
) |
|
Retrieves the specified Device Information Property (DIP) from the ZNP.
- Parameters:
-
| dip | the device information property to retrieve |
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
- Returns:
- a pointer to the beginning of the DIP payload, or a pointer to indeterminate data if error.
| unsigned char getDeviceState |
( |
|
) |
|
Retrieves the device state - indicates whether it is on the network or not.
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
- Returns:
- the device state: DEV_HOLD, DEV_NWK_DISC, DEV_ROUTER etc. or an indeterminate value if error.
| char* getDeviceStateName |
( |
unsigned char |
state |
) |
|
Retrieves the name of the device state in a human-readable format. From API Specification.
- Parameters:
-
| state | the value for the ZDO state |
- Returns:
- the name of the ZDO state
| char* getDeviceTypeName |
( |
unsigned char |
deviceType |
) |
|
Retrieves the name of the device type in a human-readable format, e.g. Coordinator, Router, or End Device.
- Parameters:
-
| deviceType | the type of device |
- Returns:
- the name of the deviceType
| unsigned char* getMacAddress |
( |
|
) |
|
Retrieves the Media Access Controller (MAC) Address (aka Long Address, aka IEEE Address) The MAC Address is an eight byte globally unique serial number for this IC.
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
- Returns:
- a pointer to the beginning of the MAC address (LSB first), or a pointer to indeterminate data if error.
| void getNetworkConfigurationParameters |
( |
|
) |
|
Utility method to display stored network configuration parameters. These are the configuration parameters stored in NV memory and are used to initialize the ZNP.
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| unsigned char getNvItemSize |
( |
unsigned char |
nvItem |
) |
|
Retrieves the size of the selected Non-Volatile (NV) memory item. NV Items 1 through 4 are 2 bytes each; 5 & 6 are 16 bytes each.
- Parameters:
-
| nvItem | which Non-Volatile memory item. Must be 1-6 inclusive. |
- Returns:
- size of the given nvItem
| unsigned int getRandom |
( |
|
) |
|
Retrieves a random number from the ZNP using SYS_RANDOM command.
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
- Returns:
- the random number, or indeterminate data if error.
| char* getResetReason |
( |
unsigned char |
reason |
) |
|
Utility method for displaying nice reset reason from a SYS_RESET_IND message.
- Parameters:
-
- Returns:
- a string containing the name of the reset reason.
| char* getSecurityModeName |
( |
unsigned char |
securityMode |
) |
|
Retrieves the name of the security mode in a human-readable format. From API Specification.
- Returns:
- the name of the securityMode
| unsigned char* getVersion |
( |
|
) |
|
Retrieves the ZNP's version information using SYS_VERSION command.
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
- Returns:
- a pointer to the beginning of the version structure, or a pointer to indeterminate data if error.
- See also:
- Interface Specification for order of fields
Displays the contents of the Znp Buffer, znpBuf. Useful for debugging ZNP communications.
| unsigned char* readNvItem |
( |
unsigned char |
nvItem |
) |
|
Retrieves the specified Non-Volatile (NV) memory item from the ZNP.
- Precondition:
- ZNP was initialized.
- Parameters:
-
| nvItem | which nvItem to write, 1 through 6 inclusive |
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
- Returns:
- a pointer to the beginning of the NV item retrieved, or a pointer to indeterminate data if error.
- Note:
- does not verify the length of the returned nvItem was what we expected
| void setCallbacks |
( |
unsigned char |
cb |
) |
|
Enable/Disabless callbacks on the ZNP.
- Parameters:
-
| cb | must be either CALLBACKS_ENABLED or CALLBACKS_DISABLED |
- See also:
- section ZCD_NV_ZDO_DIRECT_CB in ZNP Interface Specification
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| void setChannel |
( |
unsigned long |
channelMask |
) |
|
Configures the ZNP to only join a network according to the given channel mask.
- Parameters:
-
| channelMask | bitmap of which channels to use. If channelMask = ANY_CHANNEL then the radio will join a network on any channel. Default channel after a CLEAR_CONFIG is channel 11, or (MSB first) 0x00000800. |
- Note:
- : if using a packet sniffer, be sure to change the channel on the packet sniffer too or else you won't see any packets.
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| void setPanId |
( |
unsigned int |
panId |
) |
|
Configures the ZNP to only join a network with the given panId. If panId = ANY_PAN then the radio will join any network.
- Parameters:
-
| panId | the PANID to join, or ANY_PAN to join any PAN |
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| void setPollRate |
( |
unsigned int |
pollRate |
) |
|
Sets the ZCD_NV_POLL_RATE, which is used by end devices and controls how often an end device polls its associated router for new data. Default is 2000 (2 seconds). Higher numbers will increase latency but reduce average power consumption.
- Parameters:
-
| rate | how often (in mSec) to poll; must be between 1 to 65000, inclusive. |
- See also:
- section ZCD_NV_POLL_RATE in ZNP Interface Specification
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| void setSecurityKey |
( |
unsigned char * |
key |
) |
|
Loads the specified key into the ZNP. Does not change security mode, need to use setSecurityMode() too.
- Note:
- if NOT using pre-configured keys then the coordinator will distribute its key to all devices.
- Parameters:
-
| key | preConfiguredKey a 16B key to use |
- Precondition:
- setSecurityMode() called
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| void setSecurityMode |
( |
unsigned char |
securityMode |
) |
|
Configures the ZNP for the specified security mode. If securityMode = SECURITY_MODE_OFF then only ZCD_NV_SECURITY_MODE is written. Otherwise ZCD_NV_SECURITY_MODE and ZCD_NV_PRECFGKEYS_ENABLE are written.
- Note:
- if NOT using pre-configured keys then the coordinator will distribute its key to all devices.
- Parameters:
-
| securityMode | SECURITY_MODE_OFF or SECURITY_MODE_PRECONFIGURED_KEYS or SECURITY_MODE_COORD_DIST_KEYS |
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| void setStartupOptions |
( |
unsigned char |
option |
) |
|
Configures startup options on the ZNP. These will reset various parameters back to their factory defaults. The radio supports two types of clearing state, and both are supported:
- STARTOPT_CLEAR_CONFIG restores all settings to factory defaults. Must restart the ZNP after using this option.
- STARTOPT_CLEAR_STATE only clears network settings (PAN ID, channel, etc.)
- Note:
- all ZB_WRITE_CONFIGURATION commands take approx. 3.5mSec between SREQ & SRSP; presumably to write to flash inside the CC2530ZNP.
- Parameters:
-
| option | which options to set. Must be zero, STARTOPT_CLEAR_CONFIG, or STARTOPT_CLEAR_STATE. |
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| void setZigbeeDeviceType |
( |
unsigned char |
deviceType |
) |
|
Sets the Zigbee Device Type for the ZNP.
- Parameters:
-
| deviceType | the type of Zigbee device. Must be COORDINATOR, ROUTER, or END_DEVICE |
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| unsigned char sysGpio |
( |
unsigned char |
operation, |
|
|
unsigned char |
value | |
|
) |
| | |
Performs the specified General Purpose Input/Output (GPIO) operation.
- Parameters:
-
| operation | which GPIO operation to do: GPIO_SET_DIRECTION, GPIO_SET_INPUT_MODE, GPIO_SET, GPIO_CLEAR, GPIO_TOGGLE, GPIO_READ |
| value | the value to write |
- Returns:
- the value returned by the ZNP if operation = GPIO_READ; indeterminate value otherwise
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| signed int waitForMessage |
( |
unsigned int |
messageType, |
|
|
unsigned char |
timeoutSecs | |
|
) |
| | |
Waits for the specified type of message. Silently discards any other messages received. Received message will be in znpBuf[]. If the specified type of message isn't received then returns error code.
- Returns:
- 0 if success, -21 if timeout, -31 if received a message but it wasn't the type we're expecting.
| void writeNvItem |
( |
unsigned char |
nvItem, |
|
|
unsigned char * |
data | |
|
) |
| | |
Writes the specified Non-Volatile (NV) memory item to the ZNP. The contents of the selected nvItem will be overwritten from memory starting at data.
- Precondition:
- ZNP was initialized.
- Parameters:
-
| nvItem | which nvItem to write, 1 through 6 inclusive |
| data | the data to write |
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
| unsigned char* znpInit |
( |
|
) |
|
Initializes the hardware interface to the ZNP (SPI). This method must be called before any other method in the library.
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
- Returns:
- a pointer to the beginning of the version structure, or a pointer to indeterminate data if error.
- See also:
- Interface Specification for order of fields
- Todo:
- modify this if using UART
| unsigned char* znpReset |
( |
|
) |
|
Resets the ZNP using hardware and retrieves the SYS_RESET_IND message. This method is used to restart the ZNP's internal state machine and apply changes to startup options, zigbee device type, etc.
- Postcondition:
- znpResult contains the error code, or ZNP_SUCCESS if success.
- Returns:
- a pointer to the beginning of the version structure, or a pointer to indeterminate data if error.
- See also:
- Interface Specification for order of fields
Variable Documentation
This buffer will hold the transmitted messages and received SRSP Payload after sendMessage() was called.
1.6.3